<?php
// $Id: Permission.interface.php 73 2007-02-12 03:45:43Z tswicegood $
/**
 * This file contains {@link Permission} which is part of the PHP Content Repository
 * (phpCR), a derivative of the Java Content Repository JSR-170,  and is 
 * licensed under the Apache License, Version 2.0.
 *
 * This file is based on the code created for
 * {@link http://www.jcp.org/en/jsr/detail?id=170 JSR-170}
 *
 * @author Travis Swicegood <travis@domain51.net>
 * @copyright PHP Code Copyright &copy; 2004-2005, Domain51, United States
 * @copyright Original Java and Documentation 
 *  Copyright &copy; 2002-2004, Day Management AG, Switerland
 * @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, 
 *      Version 2.0
 * @package phpContentRepository
 */

/**
 * Load the {@link phpCR} library file(s)
 */ 
require_once(dirname(__FILE__) . '/../phpCR.library.php');

/**
 * The permissions used by {@link AccessManager}.
 *
 * Level 2 only
 *
 * Given a particular {@link Ticket}, a particular {@link Permission} is
 * either TRUE or FALSE of a particular {@link Node} 
 * or {@link Property}.
 *
 * This interface defines the following permissions:
 * <ul>
 *    <li>{@link Permission::ADD_NODE}</li>
 *    <li>{@link Permission::SET_PROPERTY}</li>
 *    <li>{@link Permission::REMOVE_ITEM}</li>
 *    <li>{@link Permission::READ_ITEM}</li>
 * </ul>
 *
 * Each constant is a power of 2 and thus can be set as a bitmask in an
 * integer value.
 *
 * @see Workspace::getAccessManager(), AccessManager
 * @author PHP - Travis Swicegood <travis@domain51.net>
 * @copyright Copyright &copy; 2004-2005, Domain51
 * @package phpContentRepository
 */
interface Permission 
{

    
   /**
    * Determines whether adding a {@link Node} is allowed.
    *
    * If this value is present in either {@link AccessManager::isGranted()} or
    * {@link AccessManager::getPermissions()}, then a given node's 
    * {@link Node::addNode()} is allowed.
    *
    * {@link AccessManager::isGranted()} looking for this value on a 
    * {@link Property} should always return FALSE.
    *
    * If not present, {@link AccessDeniedException} should be thrown on 
    * {@link Node::save()}.
    *
    * @var int
    * @see AccessManager::isGranted(), AccessManager::getPermissions(),
    *   Node::addNode()
    */
    const ADD_NODE = 1;
    
    
   /** 
    * Determines whether setting a {@link Property} for a {@link Node} via
    * {@link Node::setProperty()} is allowed.
    *
    * If this value is present in either {@link AccessManager::isGranted()} or
    * {@link AccessManager::getPermissions()} for a {@link Node}, then that
    * node's {@link Node::setProperty()} is allowed.
    *
    * If this value is present in either {@link AccessManager::isGranted()} or
    * {@link AccessManager::getPermissions()} for a {@link Property}, then that
    * property's {@link Property::setValue()} is allowed.
    *
    * If not present, {@link AccessDeniedException} should be thrown on 
    * {@link Node::save()}.
    *
    * @var int
    * @see AccessManager::isGranted(), AccessManager::getPermissions(),
    *   Node::setProperty(), Property::setValue()
    */
    const SET_PROPERTY = 2;
    
    
   /**
    * Determines whether removal of this {@link Item} is allowed.
    *
    * If this value is present in either {@link AccessManager::isGranted()} or
    * {@link AccessManager::getPermissions()} for an {@link Item}, then that
    * item's {@link Node::remove()} is allowed.
    *
    * This must be set on the parent {@link Node} in order to remove a 
    * {@link Node}.  See {@link Node::remove()} for a full explanation of how
    * removal should work.
    *
    * @var int
    * @see AccessManager::isGranted(), AccessManager::getPermissions(),
    *   Node::remove()
    */
    const REMOVE_ITEM = 4;
    
    
   /**
    * Determines if an a given {@link Item} can be read.
    *
    * If this value is present in either {@link AccessManager::isGranted()} or
    * {@link AccessManager::getPermissions()} for a {@link Property}, reading 
    * it via {@link Node::getProperty()} is permitted.  Note: This 
    * {@link Property} must be relative to the the given {@link Node} trying to
    * read it.
    *
    * 
    *   $m = '/example/node/property';
    *   $n = '/example/node';
    *   $mObj = $nObj->getProperty('property');
    * 
    *
    * If this value is present in either {@link AccessManager::isGranted()} or
    * {@link AccessManager::getPermissions()} for a {@link Node}, reading it
    * via {@link Node::getNode()} is permitted.  Note: This 
    * {@link Node} must be relative to the given {@link Node} trying to read it.
    *
    * 
    *   $m = '/example/parent/node';
    *   $n = '/example/parent';
    *   $mObj = $nObj->getNode('node');
    * 
    *
    * @var int
    * @see AccessManager::isGranted(), AccessManager::getPermissions(),
    *   Node::getProperty(), node::getNode()
    */
    const READ_ITEM = 8;
    
    
   /**
    * Returns the numerical constant identifying this {@link Permission}. 
    *
    * This value is always a power of 2 ((i.e. sets of permissions can be 
    * encoded as a bitmask in a integer value).
    *
    * @return int
    *   The numerical value
    * @see AccessManager::getSupportedPermissions()
    */
    public function getValue();
    
    
   /**
    * Returns the descriptive name of this permission.
    *
    * @return string
    *   The name
    * @see AccessManager::getSupportedPermissions()
    */
    public function getName();
}

